// ==================================================================================
// Shared Genomics Project MPI Codebase
// Version 1.0 30/04/2010
//
// (c) 2010 University of Manchester all rights reserved
//
// This file is distributed under the GNU General Public License, Version 2.  
// Please see the file COPYING.txt for more details
// ==================================================================================

#ifndef _PEDFILE_H_
#define _PEDFILE_H_

#include "chromosomes.h"
#include "individual.h"
#include "options.h"
#include "mapfile.h"
#include "types.h"

#ifdef __cplusplus
extern "C" {
#endif

/*!
\file
\ingroup	gio
\brief		Sample Array/Individual-Major Allelic Data
\details
	This header provides methods to store sample data (phenotype/response variable) of an entire genomic data-set.<br>
	This structure also stores Individual-major allelic data by binding the information to the \ref individual::one
	and \ref individual::two array assigned to each person in a data-set.<br>
	The \ref pedfile structure stores information read from a PLINK-compatible text files 
	and is not used in the statistical calculation codes.
*/

/*! \brief Sample Array/Individual-Major Allelic Data */
struct pedfile {
	/*! \brief Sample array */
	struct individual **sample;

	/*! \brief Size of the Sample array */
	int nSample;

	/*! \brief Storage available to the sample array */
	int sample_available;

	/*! \brief No. sample pairs. */
	int np; 
};

/*! 
\brief Reads a text pedigree file (PED).
\details
	Reads a text pedigree file with the phenotype data stored in the \ref pedfile parameter
	and the allelic data stored in the \ref mapfile parameter.<br>
	The mapfile must be read before a pedigree file can be parsed.<br>
	The path to the input PED file is bound to \ref selected_options::szPedFileName.<br>
	Allelic data is stored in the \ref mapfile parameter and phenotype data in
	the \ref pedfile parameter.
\param [in,out] ped pedfile parameter
\param [in,out] map pedfile parameter
\param [in] ops Input file location
\returns 1 on success, 0 on failure
*/
int pedfile_read(struct pedfile *ped, struct mapfile *map, struct selected_options *ops);

/*! 
\brief Insert/append a Person to the sample array.
\details
	The sample array will grow to accodomate new entries.
\param [in, out] ped pedfile parameter
\param [in, out] person New array element
\returns 1 on success, 0 on failure
*/
int pedfile_insert_sample(struct pedfile* ped, struct individual *person);

/*! 
\brief Initialise a \ref pedfile structure.
\details All dynamic arrays set to NULL and counters zeroed.
\param [in, out] ped pedfile parameter
\returns 1 on success, 0 on failure
*/
int pedfile_init(struct pedfile *ped);

/*! 
\brief Free the attributes bound to a \ref pedfile structure.
\details All dynamic arrays set to NULL and counters zeroed.
\param [in, out] ped pedfile parameter
\returns 1 on success, 0 on failure
*/
int pedfile_free_attributes(struct pedfile *ped);

/*! 
\brief Create an 'initialised' \ref pedfile structure.
\returns 1 on success, 0 on failure
*/
struct pedfile* pedfile_create();

/*! 
\brief Allocate sample array of a \ref pedfile structure.
\param [in, out] ped pedfile parameter
\param [in] size Size of the sample array
\returns 1 on success, 0 on failure
*/
int pedfile_alloc_sample(struct pedfile *ped, int size);

/*!
\brief %Set the initial permutation order of sample array
\details
	%Set the initial permutation order by setting the value of each
	\ref individual::pperson in \ref pedfile::sample to point to
	itself.
\param [in, out] ped pedfile parameter
\returns 1 on success, 0 on failure
*/
int pedfile_set_original_order(struct pedfile *ped);

/*!
\brief Apply the affected status of a binary trait to the sample array.
\param [in, out] ped pedfile parameter
\returns 1 on success, 0 on failure
*/
int pedfile_aff_coding(struct pedfile *ped);

/*!
\brief Copy a PED file to a local directory and read. 
\details
	The path to the input PED file is bound to \ref selected_options::szPedFileName.<br>
	The mapfile must be read before a pedigree file can be parsed.<br>
	Allelic data is stored in the \ref mapfile parameter and phenotype data in
	the \ref pedfile parameter.
\param [in,out] p pedfile parameter
\param [in,out] m pedfile parameter
\param [in] ops Input file location
\param [in] rank Local processor rank
\returns 1 on success, 0 on failure
*/
int pedfile_copy_and_read(struct pedfile *p, struct mapfile *m, struct selected_options *ops, int rank);

#ifdef __cplusplus
}
#endif

#endif // _PEDFILE_H_
